Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

ShowErrorMessage takes the name of the routine that has caught the error as a parameter. A more elaborate error handler might take other information from the calling routine to provide a more detailed message. It might also remind the user to record other relevant information such as the name of the form the user was viewing when the error occurred, what the user was doing, and so forth.

‘ Display an error message. If the help file
‘ and context are available, allow the user to
‘ click the Help button.
Public Sub ShowErrorMessage(routine_name As String)
Dim txt As String

    ‘ Create the error message.
     txt = MakeErrorMessage(routine_name)

    ‘ Display with or without the help button
    ‘ as is appropriate.
    If DEBUG_MODE And Len(Err.HelpFile) > 0 Then.
       MsgBox txt, _
           vbOKOnly + vbMsgBoxHelpButton, _
           “Unexpected Error”, _
           Err.HelpFile, Err.HelpContext
     Else
         MsgBox txt, vbOKOnly, “Unexpected Error”
    End If
End Sub

‘ Make an appropriate error message.
Public Function MakeErrorMessage(routine_name As String) As String
    MakeErrorMessage = _
         “Encountered an unexpected error.” & _
         vbCrLf & _
         “Please forward the following ” & _
         “information to the development team.” & _
         vbCrLf & “----------” & vbCrLf & _
         “Error ” & Format$(Err.Number) & _
         “ in ” & routine_name & “.” & _
         vbCrLf & Err.Description
End Function

You can download the ShowErrorMessage code from the book’s Web site at www.vb-helper.com/err.htm. Program ShowErr, also available at the Web site, demonstrates this method for reporting errors. Figure 13.1 shows the program displaying an error dialog.

Figure 13.1  Program ShowErr displaying an error message.

Displaying an error message like this is extremely simple. It requires very few extra resources so it is likely to succeed. For example, if the file system is full, the program may be unable to write an error message into a log file or a database, but it will be able to present an error message.

This technique has some drawbacks, however. The user must record the error information faithfully and give it to the developers promptly. Because most users are not programmers, they do not know what information is important and do not always give relevant information to developers.

This method also tells users that there is a problem. If the program can continue execution, it may not need to bother the user. In that case, it would be better to record the error quietly and let the user continue working. Later sections in this chapter explain how to record errors quietly. Of course, if the program cannot perform as the user expects, it must present some message so the user knows what is happening.

Unwind the Stack

The error messages described in the previous section provide a minimum of information. An error handler could present lots of other information such as the values of variables when the error occurred. It can also raise a new error to be handled by the calling routine. A program can use this fact to generate a trace of the sequence of subroutine calls that led to the error. It can also display the values of the variables in each of the routines in the call sequence.

To make a trace, a subroutine that detects an error saves information about itself in an error collection. It then raises the error errStackDump. Control transfers to the routine that called this one. When that routine sees the error errStackDump, it adds information about itself to the error collection and again raises the errStackDump error. Control continues moving up the stack until it reaches a routine that was triggered by Visual Basic; usually, that is an event handler. That routine uses the information in the error collection to create the stack trace. It can display the trace to the user, save it to a file, and so forth.

Program StackDmp, shown in Figure 13.2, uses this method to display stack traces. Click the option button next to the name of the routine you want to raise an error. Then click the Execute button and the program will display an appropriate stack trace.

The following listing shows the error message displayed in Figure 13.2. The comments to the right indicate the meaning of the lines in the message. In this example, subroutine Sub_A_1 started the process with a subscript out of range error.

Error 9.                   ‘ The error code.
Subscript out of rang.     ‘ The error description.

Stack dump:
> cmdExecut                ‘ Routine cmdExecute called Sub_A.
     txt = In cmdExecut.   ‘ The value of txt in cmdExecute.
     > Sub_A               ‘ Routine Sub_A called Sub_A_1.
       txt = In Sub_A      ‘ The value of txt in      Sub_A.
       > Sub_A_1           ‘ Sub_A_1 raised the error.
       txt = In Sub_A_1    ‘ The value of txt in Sub_A_1.

Figure 13.2  Program StackDmp displaying a stack trace.

Program StackDmp uses the RoutineInfo class to record information about routines. As errStackDump errors make control pass up the stack, each routine records information about itself using RoutineInfo objects.

The following code shows how the RoutineInfo class stores information about a routine. The TextValue function returns a textual representation of the information indented by a specified amount. The program uses this value to build the stack trace message.

‘ A class to hold information about a routine.
Option Explicit

Private RoutineName As String
Private VariableValues As New Collection

‘ Save the routine's name.
Public Sub SaveName(ByVal routine_name As String)
    RoutineName = routine_name
End Sub

‘ Add a variable value string.
 Public Sub SaveValue(ByVal variable_name As String, _
    ByVal variable_value As String)

    VariableValues.Add variable_name & “ = ” & _
        variable_value
End Sub

‘ Return a textual representation of the stack.
Public Function TextValue(ByVal num_spaces As Integer) As String
Dim result As String
Dim spaces As String
Dim variable_value As Variant

     ‘ Start with the routine's name.
     result = Space(num_spaces) & “> ” & _
         RoutineName & vbCrLf

    ‘ Build a string listing the variable values.
     spaces = Space(num_spaces + 4)
     For Each variable_value In VariableValues
         result = result & spaces & _
             variable_value & vbCrLf
    Next variable_value

    TextValue = result
End Function